Writing Health Correlation Data#

In the Scripting app, you can write correlated health data to Apple HealthKit using the global HealthCorrelation.create() method and Health.saveCorrelation(). A correlation represents a relationship between multiple health samples, such as a blood pressure reading that includes both systolic and diastolic values, or a meal record that includes nutritional quantities.

This guide explains how to create and save a correlation sample.

What Is a Correlation?#

A correlation groups related health data samples into a single, logical record. HealthKit currently supports the following correlation types:

• "bloodPressure" — includes two quantity samples: "bloodPressureSystolic" and "bloodPressureDiastolic"
• "food" — can include multiple nutritional quantity samples such as calories, protein, carbohydrates, etc.

1. Create Related Quantity Samples#

Before creating a correlation, you must first create the individual HealthQuantitySample instances that will be included.

Example: Blood Pressure Samples#

1const systolic = HealthQuantitySample.create({
2  type: "bloodPressureSystolic",
3  startDate: new Date(),
4  endDate: new Date(),
5  value: 120,
6  unit: HealthUnit.millimeterOfMercury()
7})
8
9const diastolic = HealthQuantitySample.create({
10  type: "bloodPressureDiastolic",
11  startDate: new Date(),
12  endDate: new Date(),
13  value: 80,
14  unit: HealthUnit.millimeterOfMercury()
15})

Check that both samples are not null before proceeding.

2. Create the Correlation#

Use HealthCorrelation.create() to group the samples into a correlation.

Parameters#

• type: "bloodPressure" or "food"
• startDate: Start of the event
• endDate: End of the event
• objects: An array of HealthQuantitySample (or HealthCategorySample) instances to include
• metadata (optional): Additional metadata (e.g., source, context)

Example#

1const correlation = HealthCorrelation.create({
2  type: "bloodPressure",
3  startDate: systolic.startDate,
4  endDate: systolic.endDate,
5  objects: [systolic, diastolic],
6  metadata: {
7    source: "ScriptingApp"
8  }
9})
10
11if (!correlation) {
12  throw new Error("Failed to create correlation.")
13}

3. Save the Correlation to HealthKit#

Use Health.saveCorrelation() to persist the correlation data to the HealthKit store.

1await Health.saveCorrelation(correlation)

Full Example: Writing a Blood Pressure Correlation#

1async function writeBloodPressure() {
2  const systolic = HealthQuantitySample.create({
3    type: "bloodPressureSystolic",
4    startDate: new Date(),
5    endDate: new Date(),
6    value: 120,
7    unit: HealthUnit.millimeterOfMercury()
8  })
9
10  const diastolic = HealthQuantitySample.create({
11    type: "bloodPressureDiastolic",
12    startDate: new Date(),
13    endDate: new Date(),
14    value: 80,
15    unit: HealthUnit.millimeterOfMercury()
16  })
17
18  if (!systolic || !diastolic) {
19    console.error("Failed to create samples.")
20    return
21  }
22
23  const correlation = HealthCorrelation.create({
24    type: "bloodPressure",
25    startDate: systolic.startDate,
26    endDate: systolic.endDate,
27    objects: [systolic, diastolic],
28    metadata: {
29      note: "Manually recorded",
30    }
31  })
32
33  if (!correlation) {
34    console.error("Failed to create correlation.")
35    return
36  }
37
38  try {
39    await Health.saveCorrelation(correlation)
40    console.log("Blood pressure data saved.")
41  } catch (err) {
42    console.error("Failed to save:", err)
43  }
44}
45
46writeBloodPressure()

Notes#

• All quantity samples in the correlation must have matching or consistent time ranges.

• For "bloodPressure", the correlation must include both systolic and diastolic samples.

• For "food", you may include multiple samples like:

  • "dietaryEnergyConsumed" → HealthUnit.kilocalorie()
  • "dietaryProtein" → HealthUnit.gram()
  • "dietaryCarbohydrates" → HealthUnit.gram()

• Correlation creation returns null if invalid or incomplete.